 |
Kenexa XML Integrations |
Kenexa XML
Integrations
SSO Talent Gateway Integrations:
Before beginning an SSO enabled Talent
Gateway implementation, the client should review the following lists,
which describe the integration tasks performed by Kenexa and those
performed by the client. The remaining sections in this document describe
each checklist item in more detail. 1.1
Tasks Performed by the
Client ·
The client is responsible for authenticating
its internal candidates and may use any authentication mechanism to do so.
Let Kenexa know which external method you will use to authenticate
candidates who access the Gateway. See Section 3.1 “Client Authentication
Mechanisms” for additional details. ·
Customize the sample XML provided by Kenexa
and incorporate it into your SSO integration. See “XML Details” in Section
6 for more information. ·
Determine which candidate forms (if any) will
be used to pre-populate information on the Gateway. Kenexa creates and
customizes the candidate integration form, but you must decide which
fields will be included on the form. See “Candidate Integration Forms” in
Section 5 for additional details. ·
Write customized messages that users see when
they attempt to access the Gateway directly and when they log out. Kenexa
implements the messages, but you must provide the content. See “Customized Gateway
Text” in Section 4.1 for additional
details. ·
Create one or more public keys, each with its
own start date/time. The client is responsible for maintaining its private
keys on its own servers and for using the correct key during each SSO
exchange. See “Encryption” in
Section 3.2 for more information. ·
Handle all errors and failed requests. See
“Processing and
Error Handling” on Section 6.3 for more
information. ·
Confirm that the Talent Gateway site is
SSL-enabled and the site requires SSL encryption. ·
Import the client’s public keys into Kenexa
Recruiter BrassRing, and then specify keys to associate with the SSO
application using internal configuration tools. ·
Create and customize candidate integration
forms, based on information received from the
client. ·
Implement customized messages that users see
when they attempt to access the Gateway directly and when they log out,
based on content received from the client. ·
Once the SSO enabled Talent Gateway is
configured, Kenexa generates sample integration XML specific to the
Gateway and sends the XML to the client. ·
For an additional fee Kenexa will convert the
existing Talent Gateway profiles for client’s Internal Gateways over to
SSO. Migrations of Talent Gateway profiles are performed by mapping the
existing profiles with the SSO ID of the users in your system. SSO ID is
described later in the document. Talent Gateway SSO is
provided as a hosted XML web service that allows a client to send a
request to Kenexa Recruiter BrassRing to confirm the validity of an
authenticated user’s identity and grant them access to an organization’s
internal or employee referral Talent Gateways. SSO enabled Talent Gateways
also let an organization pre-populate Talent Gateway forms with data from
a client’s HRIS, making it easier and faster for candidates to complete
applications. Pre-populated data can be editable, displayed in read-only
format, or passed through to the Gateway without being displayed to the
candidate. When an in-house
candidate clicks the Talent Gateway link on the client’s Intranet site or
system, the client system authenticates the candidate and sends an XML
request that contains the following information about an authenticated
user who is to be granted access to the Gateway: ·
an unique identifier – this could be any
unique identifier such as an HRIS ID or email address or network id or SSO
ID. ·
a timestamp – This must be in GMT time zone.
If the SSO request when processed is plus or minus 5 minutes to GMT, then
an error is thrown in the response as the web service detects that the
request was timed-out. This is also done for security reasons. If the request is
successfully validated, Kenexa Recruiter BrassRing creates a Gateway
session for the candidate and returns a redirect URL in the synchronous
response. When the client receives the response, the candidate is
redirected to the Talent Gateway and automatically logged in. The
candidate’s unique identifier is stored at the Gateway level where it is
used to identify the candidate upon all subsequent return visits to the
Gateway, whether or not the candidate creates a profile or submits to a
job. NOTE: When a Talent Gateway is
configured for SSO, it becomes the only way to access the Gateway.
Everyone who accesses the Gateway must be validated and authenticated
through an external system. There will be no other way to access the
Gateway but through the external system’s SSO portal. 2.1
Client Authentication
Mechanisms The client is responsible
for authenticating its internal candidates and may use any authentication
mechanism to do so. Here are some examples of possible authentication
mechanisms: ·
Username/password authentication against a
database maintained by the client ·
Microsoft™ Windows™ domain
authentication ·
Oracle™ authentication ·
SAP™ authentication This list is by no means
exclusive. The client may
authenticate users however it wishes, as long as each user is properly
authenticated by the client before the user’s identity is submitted to
Kenexa Recruiter BrassRing. The data exchanged
between Kenexa Recruiter BrassRing and the client’s servers must be
encrypted with RSA encryption. For more details on encryption specifics,
key management, etc. please refer to the Kenexa RSA Encryption Application
Guide. RSA Public Key
<PublicKey>
<RSAKeyValue>
<Modulus>rYVD4U1X3b3ELej5xH299lEEDmcMIG8Q26FCs0/7oa0o9zs7IzE=</Modulus>
<Exponent>AQAB</Exponent>
</RSAKeyValue>
</PublicKey>
<PrivateKey>
<RSAKeyValue>
<Modulus>rYVDElTW4U1X3b3ELej5xH299lEEDmcMIG8Q26FCs0/7oa0o9zs7IzE=</Modulus>
<Exponent>AQAB</Exponent>
<P>40HzAA8HjHzXI5MO3tWbS/6cJS/NnFOg7Q==</P>
<Q>DefRjIiRVQePi8A/dYI8iHnDoN7sZW0dOOtr2kVsjnQ==</Q>
<DP>VSzbKINEM9LK114V6U9hv2wpdwIemHcufIPcY0tEtb21jeV4rQ==</DP>
<DQ>uM3SilhdVI50s7D6UqOsyh+VxFdPgMxrIVXp8V0HX6np+R/cGQ==</DQ>
<InverseQ>SEahBDm8KwKnv+CfD9DE6vaByzBMoLaSju1Dau/k2FPtoSxyiVdQ==</InverseQ>
<D>m17qlmIAj0bWF3h9lZZWwn+o5OlGrf5VWjw0fTKXp+puehgLWbBk4HFGE=</D>
</RSAKeyValue>
</PrivateKey> This
section provides some guidelines for planning SSO-enabled Talent Gateways.
Kenexa creates and customizes the Gateway, with input from the client. When
creating or customizing a Gateway, remember that: ·
An SSO-enabled Talent Gateway cannot be
specified as another Gateway’s default Talent Gateway for send-to-a-friend
functionality. ·
SSO-enabled Talent Gateways must be Full
Gateways. SSO capabilities are not available for Basic
Gateways. You
can customize the text on a Talent Gateway to display
organization-specific messages. The client provides Kenexa with the
customized messages and Kenexa associates them with the Talent
Gateway. Customized messages can be up to 4,000 characters
long and can include HTML formatting. To provide more information, you can
design and create a landing page and include a link in the message that
users can click to display the page. For
SSO-enabled Talent Gateways, you’ll want to customize the following
messages: ·
Restricted SSO access message explains that
access to the site is restricted. This message is displayed to any
individual attempting to access the Gateway without going through the SSO
authentication process. ·
SSO logout confirmation message explains that the
user is logged out of the Gateway site. This message is displayed to any
individual who logs out of the Gateway or who accesses a Gateway site that
has been configured to not keep candidates always logged in. Note:
Because users don’t log into SSO-enabled Talent Gateways, you don’t have
to worry about customizing the Log in and Create Login messages. These
messages are not used with SSO enabled Talent Gateways. Forms enabled for use on a SSO-enabled Talent Gateway
allow the Gateway to pull information, such as the candidate’s current job
title, from an external system, such as the client’s HRIS. This
functionality is most useful when the candidate is an existing employee of
the client and some of the information being requested on the Gateway
already exists in a client-side system. This way, the candidate does not
have to enter the information; the information is automatically sent
through the Gateway. Integrated forms data is displayed on the Additional
Information screen for the Submit Resume/CV or Apply to Job
workflow. If a candidate selects a position for which a Gateway
Questionnaire has been configured, forms data is displayed on a screen
that appears before the first step in the Gateway Questionnaire process.
Note: In
this release, you cannot use candidate integration forms data to
pre-populate the personal information, experience, or education sections
or pre-populate the answers to Gateway Questionnaire questions. With
the Employee Referral Talent Gateway, having an Employee Referral Data
Form is mandatory. This form in the minimum contains the FirstName,
LastName and the Email of the person who is referring someone. For
more information, see “Sending Forms Information in XML Requests” on
page 13. 4.1
Valid Forms for SSO
Integration Any
candidate form is valid for use with SSO-enabled Talent Gateways. You may
work with your Kenexa representative to determine which forms cannot be
both a Gateway integration form and a 'per requisition' type form (single
or multiple per candidate/per requisition). Tip: You can
associate multiple forms with a single SSO enabled Talent Gateway, but
Kenexa recommends that you design a single form that contains all the
fields whose data you’ll want to use to populate the Gateway. Once this
process is complete, Kenexa configures the form as a Gateway candidate
integration form. 4.2
How Forms Data Appears to
Candidates Candidate integration form data that is sent through
the Gateway can be configured on a field-by-field basis as: ·
Read-only. The candidate sees but cannot edit
the data before it is sent. ·
Editable. The candidate sees and can edit the
data before it is sent. ·
Hidden. The data is sent through the Gateway,
but the candidate never sees it and is not notified that the data was
sent. The
hosted web service uses XML messages to pass user information and forms
data to Kenexa Recruiter BrassRing. Once the SSO enabled Talent Gateway is
configured, Kenexa generates sample integration XML specific to the
Gateway and sends the XML to the client. The client can then customize the
XML and incorporate it into their SSO integration. 5.1
Sending Forms Information in XML
Requests When
you integrate a candidate form with a SSO enabled Talent Gateway, you must
specify the form details in the XML request. The
<Form> element identifies the form that
contains the information that will pre-populate the Gateway. For each
<Form> node, one or more <FormInput> elements identify the form
fields whose data will populate the Gateway; the request contains one
<FormInput> element for each form field. The
<Form> element identifies the form to integrate with the SSO enabled
Talent Gateway. 5.1.1.1
Usage <Form
FormTypeId=”xsd:string” FormName=”xsd:string” /> 5.1.1.2
Parent Elements <Forms> 5.1.1.3
Child Elements <FormInput> 5.1.1.4
Attributes
Attribute Required? Description FormTypeId Required The form ID.
The web
service validates the form ID to make sure that the form is: ·
An active form in the client’s system ·
Attached to the associated Gateway ·
Designated as a candidate integration form for
the Gateway If the form
is not attached to the associated Gateway, the web service checks to
see if the Gateway is a member of a Global Talent Gateway (GTG). If
the Gateway is a member of a GTG and FormTypeId corresponds to an
attached form for one of the other members, then validation
succeeds. Otherwise, validation fails. FormName Optional The name
(database title) of the form. FormName is
not validated and so it can be left blank. However, including the
name of the form serves as a useful piece of documentation. The
<FormInput> element identifies a field whose data is used to
populate the SSO enabled Talent Gateway. 5.1.2.1
Usage <FormInput FieldId=”xsd:string”
FieldLabel=”xsd:string”
DisplayMode=”xsd:displayModeType” /> 5.1.2.2
Parent Elements <Form> 5.1.2.3
Child Elements None 5.1.2.4
Attributes
Attribute Required? Description FieldId Required The field ID.
The web
service validates the field ID to make sure that the field is a
valid field on the form specified by FormTypeID in the parent
<Form> node. FieldLabel Optional The name of
the field. FieldLabel is
not validated and so it can be left blank. However, including the
name of the field serves as a useful piece of documentation. DisplayMode Required Determines
how the field data that is passed to Kenexa Recruiter BrassRing
appears in the Gateway. Must be one of the following: ·
readonly specifies that candidate can see but not edit
the field data in the Gateway ·
hidden specifies that the candidate never sees the
field data in the Gateway ·
read write specifies that the candidate can both see and
edit the field data in the Gateway Misc Required Leave blank
unless the Gateway is a Referral Gateway. For Referral
Gateways, identifies the employee who made the referral. Must be one
of the following: ·
rfn specifies the referrer’s first name ·
rln specifies that the referrer’s last name ·
rem specifies the referrer’s email address The XML must
contain all three miscellaneous attribute values. See “Example for a Employee Referral Gateway”
on page 16 for more information. 5.1.2.5
Remarks Form
data does not persist in the Gateway after it is sent through to Kenexa
Recruiter BrassRing. This is true even if the data is configured as
editable and the candidate changes it before submitting it. The
following XML snippet uses data from two fields, Label1 and SampleID, from
a form called Internal Employee Sample Data Form whose Form ID is 21. The
data from these fields is populated to the SSO enabled Talent Gateway in
read-only format; the candidate can see the data but cannot change it. <Forms> <Form formtypeid="21" formname="Internal Employee Sample Data Form"> <FormInput fieldid="4820" fieldlabel="Label1"
displaymode="readonly" misc="">
<![CDATA[Response for ::General Employee
Information]]> </FormInput> <FormInput fieldid="4821" fieldlabel="SampleID" displaymode="readonly" misc="">
<![CDATA[Response for ::Sample ID:: came from SSO
Integration]]> </FormInput> </Form> </Forms> 5.1.3.1
Example for a Employee Referral
Gateway The
following XML snippet, for a Referral Gateway, passes the name and email
address of an employee who made a referral. While implementing SSO on the
ERG gateway, it is mandatory to pass the below information in the SSO XML.
In the example below, you will notice FirstName, LastName and Email
Address are being passed. The formtypeID and the fieldID values will be
provided at the time of implementation as they are customized for every
client. <Forms> <Form formtypeid="43" formname="Employee Referral Sample Data Form"> <FormInput fieldid="4301" fieldlabel="Referred by (first name)"
displaymode="readonly" misc="rfn">
<![CDATA[Robert]]> </FormInput> <FormInput fieldid="4302" fieldlabel="Referred by (last name)" displaymode="readonly" misc="rln">
<![CDATA[Foley]]> </FormInput> <FormInput fieldid="4303" fieldlabel="Email address" displaymode="readonly" misc="rem">
<![CDATA[rfoley@anyco.com]]> </FormInput> </Form> </Forms> This
self-documented XML sample sends user credentials for validation by
Kenexa, logs an internal candidate onto an SSO enabled Gateway, and
enables the candidate form Internal Employee Data Form. The sample XML is
customized for every client and will be provided by the technical resource
that you will be working with at the time when the project begins. The
below XML gives you a sense of the actual XML. <?xml version="1.0"?> <Envelope version="01.00" xmlns:xsi="http://www.w3.org/2000/10/XMLSchema-instance">
<Sender>
<Id/>
<Credential>1000</Credential> <!-- This is constant for a given client.
Never change this -->
</Sender>
<Recipient>
<id type=""/>
</Recipient>
<TransactInfo transactType="data">
<transactId/>
<timeStamp>2007-08-28 06:35:03.510</timeStamp>
</TransactInfo>
<Packet>
<PacketInfo packetType="data">
<PacketId>1</PacketId>
<Action/>
<Manifest/>
<PacketCode/>
</PacketInfo>
<Payload>
<BrassRing>
<SiteId>456</SiteId> <!—The Site ID will be provided later at time of actual
testing. It is the Gateway ID as configured on the Kenexa system. This
never changes for an given environment-->
</BrassRing>
<EncryptedData Type="http://www.w3.org/2001/04/xmlenc#Element" xmlns:xsi="http://www.w3.org/2001/04/xmlenc#">
<EncryptionMethod Algorithm="http://www.w3.org/2001/04/xmlenc#rsa-1_5"/>
<CipherData>
<CipherValue>
<!-- <TGIntegration node below is RSA encrypted
-->
<TGIntegration>
<SsoNodes>
<SsoId>tcruise</SsoId>
<!-- this is a unique identifier of the
candidate on the client HRIS -->
</SsoNodes>
<TimeStamp>2007-08-28 06:35:03</TimeStamp>
</TGIntegration>
</CipherValue>
</CipherData>
</EncryptedData>
<Signature xmlns="http://www.w3.org/2000/09/xmldsig#">
<SignedInfo>
<SignatureMethod Algorithm="http://www.w3.org/2000/09/xmldsig#rsa-sha1"/>
</SignedInfo>
<SignatureValue>RSA signature goes here</SignatureValue>
</Signature>
</Payload>
</Packet> </Envelope> 5.2.1
Timestamp Format for Request <Timestamp> node within <TGIntegration>
node must be in GMT time zone. If the SSO request when processed is plus
or minus 5 minutes to GMT, then an error is thrown in the response as the
web service detects that the request was timed-out. This is done for
security reasons. The format of the timestamp must be YYYY-DD-MM
HH:MM:SS. 5.2.2
Timestamp Format for Response When the Response is sent back from the Web service
to the client, the Timestamp sent back in the response is Eastern Standard
Time, not GMT. 5.3
Processing and Error
Handling This
section includes the following information: ·
Sample success response ·
Sample failure response ·
Guidelines for resubmitting failed
transactions The
nodes within the XML are processed in a linear order. If the XML is
successfully validated, a success response like the one that follows is
returned synchronously: <Envelope version="01.00"> <Sender> <Id/> <Credential>1000</Credential> </Sender> <Recipient> <Id/> </Recipient> <TransactInfo transactType="response"> <TransactId>3368XYZ</TransactId> <TimeStamp>2005-08-03T12:20:18.000000-0400</TimeStamp> </TransactInfo> <Packet> <PacketInfo packetType="response"> <PacketId>1</PacketId> <Action/> <Manifest/> </PacketInfo> <Payload> <EncryptedData xmlns="http://www.w3.org/2001/04/xmlenc#">
<EncryptionMethod Algorithm="http://www.w3.org/2001/04/xmlenc#rsa-1_5"/>
<CipherData>
<CipherValue>
<!-- Encrypt the Response Node below -->
<!--<Response>
<Status>
<Code>200</Code>
<ShortDescription>Success</ShortDescription>
<LongDescription>We have successfully received the Sso
Integration XML. Please redirect the candidate to the
embedded URL in
this response for the automatic login.</LongDescription>
</Status>
<CandidateRedirectURL>http://jobs.brassring.com/ssotg.aspx?tokenid=asdfasfdasas123123asdase213423asdasdasa218asd135asd46a</CandidateRedirectURL>
</Response>-->
</CipherValue>
</CipherData> </EncryptedData> <Signature xmlns="http://www.w3.org/2000/09/xmldsig#">
<SignedInfo>
<SignatureMethod Algorithm="http://www.w3.org/2000/09/xmldsig#rsa-sha1"/>
</SignedInfo>
<SignatureValue>...</SignatureValue> </Signature> </Payload> </Packet> </Envelope> If
an error is detected during validation, the entire message is rejected and
an error response like the one that follows is returned synchronously: <Envelope version="01.00"> <Sender> <Id/> <Credential>25037</Credential> </Sender>
<Recipient> <Id/>
</Recipient>
<TransactInfo transactType="response"> <TransactId>3368XYZ</TransactId> <TimeStamp>2005-08-03T12:20:18.000000-0400</TimeStamp>
</TransactInfo>
<Packet> <PacketInfo packetType="response">
<PacketId>1</PacketId>
<Action/>
<Manifest/>
</PacketInfo>
<Payload> <EncryptedData xmlns="http://www.w3.org/2001/04/xmlenc#">
<EncryptionMethod Algorithm="http://www.w3.org/2001/04/xmlenc#rsa-1_5"/>
<CipherData>
<CipherValue>
<!-- Encrypt the Response Node below -->
<!--<Response>
<Status>
<Code>405</Code>
<ShortDescription>Failure</ShortDescription>
<LongDescription>Sso Integration has failed. A valid client
ID is required.</LongDescription>
</Status>
<CandidateRedirectURL/>
</Response>-->
</CipherValue>
</CipherData> </EncryptedData>
<Signature xmlns="http://www.w3.org/2000/09/xmldsig#"> <SignedInfo>
<SignatureMethod Algorithm="http://www.w3.org/2000/09/xmldsig#rsa-sha1"/>
</SignedInfo>
<SignatureValue>...</SignatureValue>
</Signature> </Payload>
</Packet> </Envelope> 5.3.3
Analyzing Failed
Requests If
an error is detected during validation of an integration XML request, the
entire message is rejected and a failure response is returned
synchronously. Failure responses include the following information in the
<Status> node to help you diagnose the error: ·
The <Code> element contains the HTTP
status code associated with the outcome of the request. See “6.3.3.1HTTP
Status Codes” on page 20 for more information. ·
The <ShortDescription> element simply
indicates that the request failed. ·
The <LongDescription> element contains a
descriptive error message that describes the reason the request
failed. All
synchronous responses sent by Kenexa Recruiter BrassRing in XML
integration – both success responses and failure responses – include one
of the following HTTP status codes:
HTTP Status
Code Description 200 The request
sent by the client was successful. 401 Access was
denied because of a security or authentication problem. This type of
error might occur while Kenexa and the client are setting up the
integration in a test environment. 405 All failures
related to anything other than security and authentication. When the
<Code> for a failure response is 405, check the detailed error
message in <LongDescription> to see if the error is the result
of: ·
A permanent condition that must be fixed before
the request can be resubmitted. For example, the request did not
include the authenticated user’s email address. ·
A transient condition for which retrying the
request is appropriate. For example, there was a system problem like
a database timeout. 5.3.3.2
Retrying Failed Requests If
the system responds to the request with a system error or gives no
response from the system at all, the client should retry the request up to
five times. The
SSO scenario differs from other types of integration scenarios because
submissions for most integrations are automated. For SSO, a user is
actually at his or her computer, clicking a Gateway link, so a large
number of retries and any waits between retries are not acceptable. This
section lists all the error messages that Kenexa Recruiter BrassRing could
return for SSO implementations. 5.3.4.1
General XML Validation Error
Messages ·
We have successfully received the candidate
XML. Once the xml is processed and the data is loaded, another message
will be send to you in the form of communication you have
selected. ·
Candidate XML processing failed for resumekey
: <RESUMEKEY> of transaction : <TRANSACTIONID> at
<TRANSACTIONTIME>. ·
SSO XML is empty. ·
Unexpected system error occurred. ·
Data could not be decrypted and validated.
Security exception generated. ·
Invalid xml. ·
Invalid Credential ·
Invalid SiteId ·
Invalid SsoId ·
The Client ID or Key Group Name cannot be
validated against the Site ID provided. ·
Invalid xml. A valid SsoId is
required. ·
Invalid xml. Invalid or unexpected nodes
present under
/Envelope/Packet/Payload/EncryptedData/CipherData/CipherValue/
TGIntegration node. ·
SiteId does not follow expected path:
/Envelope/Packet/Payload/BrassRing/SiteId. ·
Credential does not follow expected path:
/Envelope/Sender/Credential. ·
TGIntegration does not follow expected path:
//CipherData/CipherValue/TGIntegration. ·
SsoId does not follow expected path:
//CipherData/CipherValue/TGIntegration/SsoNodes/SsoId. ·
CipherData TimeStamp does not follow expected
path: //CipherData/CipherValue/TGIntegration/TimeStamp. 5.3.4.2
Encryption Error Messages ·
Invalid EncryptedData ·
EncryptionMethod not supported ·
Invalid CypherData TimeStamp ·
EncryptionMethod not supported ·
Invalid Signature ·
SignatureMethod not supported. ·
Invalid SignatureValue. 5.3.4.3
Candidate Integration Forms Error
Messages ·
formtype id [FORMTYPEID]: Invalid
formtypeid ·
fieldid [FIELDID]: Invalid fieldid ·
fieldid [FIELDID]: Duplicate fieldid
provided. ·
fieldid [FIELDID]: Invalid
displaymode ·
fieldid [FIELDID]: Invalid misc
value ·
Duplicate misc value provided
for:[FIELDIDLIST] ·
Distinct "rfn", "rln" and "rem" misc values
are required. ·
fieldid [FIELDID]: Value must be
numeric ·
fieldid [FIELDID]: Max length = 10 ·
fieldid [FIELDID]: Max length =
4000 ·
fieldid [FIELDID]: Max length = 255 ·
fieldid [FIELDID]: Invalid SSN
format. ·
fieldid [FIELDID]: Invalid email
format. ·
fieldid [FIELDID]: Invalid date
format. ·
fieldid [FIELDID]: Invalid field value
provided. ·
fieldid [FIELDID]: Invalid
delimiter. ·
fieldid [FIELDID]: Invalid displaymode
provided.
The following illustration shows an example of
forms data that is displayed on the Additional Information screen. The
current job level, current job title, current manager, and current
manager’s phone extension are all read-only; however, the candidate can
edit the contents of the Additional Integration Field text box.
| © 2008 Kenexa |